---
title: TurtleBot4 Basic Setup
description: "TurtleBot4 Basic Setup"
---

## Suggested Operating System Versions

OM1 only supports TurtleBot4 with Humble and Create3 with H.2.6.

Turtlebot4 Onboard:

- Ubuntu 22.04.4 LTS (GNU/Linux 5.15.0-1073-raspi aarch64) - combined with turtlebot4 humble image.
- [turtlebot4_standard_humble_1.0.4.img (2024-08-19 16:59 2.2G)](http://download.ros.org/downloads/turtlebot4/turtlebot4_standard_humble_1.0.4.zip), 
NOTE: choose turtlebot4 lite image file if your turtlebot4 is lite version.
- Create3 firmware:
[H.2.6 (Humble)](https://github.com/iRobotEducation/create3_docs/releases/download/H.2.6/Create3-H.2.6.swu)
- Docker

## Prepare the Turtlebot4

1. Flash the turtlebot4 image to an SD card if needed.
2. Upgrade/downgrade the Create3 firmware to H.2.6 if needed.
3. Insert the SD card into the Turtlebot4 and power it on.
4. Set up your TurtleBot4 following the [Basic Setup](https://turtlebot.github.io/turtlebot4-user-manual/setup/basic.html#robot). 

NOTE: For above step 4, you don't need to configure **User PC** unless you want to use the ROS2 to control the TurtleBot4.

## Identity and Keys

**API_KEY** Go to [portal](https://portal.openmind.org/) to get a free API key. Enter this API key in the "api_key" field in the `/config/turtlebot4.json5` file. You can also provide this API key via your .env - just enter it as:

```bash
OM_API_KEY=om1_live_e4252f1cf005af...
```

**UNIVERSAL_ROBOT_ID (URID)** Go to["Hello Robots, come join us"](https://portal.openmind.org/robots) to join a decentralized machine\<\>machine coordination and communication system (FABRIC). Enter machine metadata - currently an arbitrary string - and click "join". The system will provide a unique URID for your robot. The URIDs all share the same format: they begin with `OM`, then 12 alphanumeric characters (numerals and letters), adding up to 14 characters in total. They're not case sensitive. A unique URID allows multiple robots to communicate with one another, similar to how humans use different phone numbers to help them communicate and coordinate.

Enter the URID in the "URID" field in the `/config/turtlebot4.json5` file. You can also provide the URID via your .env - just enter it as:

```bash
URID=OM742d35Cc6634 # yours will be different!
```

## Configure the Turtlebot4

Once the Turtlebot4 is set up, you can configure it as follows:

- configure on turtlebot4 onboard RPi4 through `turtlebot4-setup`
- configure on turtlebot4 onboard Create3 through web server
- install docker and configure the docker-compose.yaml file 

### Configure the Turtlebot4 onboard RPi4

As you have just experienced first-hand, there are numerous issues connecting to a TurtleBot4 in a university/enterprise network. To solve many of those, we follow the dual Zenoh bridge approach developed by [theconstruct.ai](https://www.theconstruct.ai/), which is to give the Raspberry Pi and the Create3 their own ROS2 DOMAIN_IDs, and then use Zenoh bridges to filter message traffic between the RPi and the Create3. This allows you to filter messages on a per topic level (see the `config_create3.json5` file for an example of how this is done).

Make the following `ROS_DOMAIN_ID` changes to the TurtleBot4. Use the `turtlebot4-setup` tool to access `ROS Setup:Bash Setup` and set it to the following:

```bash
ROBOT_NAMESPACE=/_your_robot_URID_/pi 
# example: ROBOT_NAMESPACE=/OM742d35Cc6634/pi
ROS_DOMAIN_ID=0
RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
CYCLONEDDS_URI=[] # Empty
```

Click "Save", "Esc", and then "Apply Settings". The TurtleBot4 will reboot. 

### Configure the Turtlebot4 onboard Create3

Once the reboot is complete (wait for chime, 1 min), access the Create3's App config page at its web server (e.g. `192.168.1.XXX:8080/ros-config`). Change the ROS_DOMAIN_ID to 1. The correct settings are:

```
ROS 2 Domain ID (default 0): 1
ROS 2 Namespace: /_your_robot_URID_/c3 
# example: /OM742d35Cc6634/c3
RMW_IMPLEMENTATION: rmv_cyclonedds_cpp
```

- Note1 : the use of the "/c3" to create an unique namespace for the c3.
- Note2 : _your_robot_URID_ is the URID of your robot, and it is the same as the URID of your OM1 robot.  

Click `Save` and _Restart Application_.

NOTE: Do not forget to click _Restart Application_, otherwise the changes will not be applied. Wait for chime (1 min) indicating Create3 reboot.

### Install docker and configure the docker-compose.yaml file 

Finally, on the TurtleBot4's RPi, [install Docker](https://docs.docker.com/engine/install/ubuntu/) and run `sudo docker compose -f docker-compose.yaml up -d`. The `docker-compose` should be:

```bash docker-compose.yaml
services:
  zenoh-bridge-turtlebot4:
    image: openmindagi/turtlebridge
    container_name: zenoh-bridge-turtlebot4
    network_mode: "host"
    restart: always # Ensures the container restarts on reboot
```

The TurtleBot4 will now be more stable, can discover other computers running **Zenoh**, send them **Zenoh** messages, and also, accept **Zenoh** messages and forward them to **ROS2**.

## OM1 Installation and launch

You can install and run OM1 

- offboard (your laptop) or
- onboard (Raspberry Pi, on Turtlebot4)

**NOTE**: Before running OM1, double check the [following configurations](#identity-and-keys):

- API Key
- URID


### Run OM1 onboard (Raspberry Pi) on Turtlebot4  

Once the TurtleBot4 is set up, in order to use the hardware (like camera, microphone, speaker, LIDAR etc. ) of the Turtlebot4, you can install OM1 on the Turtlebot4.

**Important: Make sure your Raspberry Pi 4 is running Ubuntu 22.04.4 LTS (Turtlebot4 Humble image) and that the Create 3 is running H.2.6/Create3-H.2.6.swu** (see [Suggested Operating System Versions](#suggested-operating-system-versions)). Among other possible problems, running Ubuntu 24 will create compatibility issues with the version of ROS2 and CycloneDDS on the Create 3. 

On the RPi terminal command line, follow [instructions](/getting-started/raspberrypi). When you see all the right topics listed in `ros2 topic list`, your TurtleBot4 is set up and you are ready to install OM1.

* Install `uv` - Python package manager.   
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

* Install `portaudio`, `ffmpeg` and other dependencies

```bash
sudo apt install pulseaudio pulseaudio-utils ffmpeg portaudio19-dev python-all-dev
```

* Connect a Logitech 270 Webcam (or equivalent).

* Unplug the standard TurtleBot4 Depth Camera. 

* Connect a speaker to RPi with a 3.5 mm audio patch cable (or use bluetooth, depending on your pain threshold and patience with debugging bluetooth issues).

* Make sure [Identity and Keys](#identity-and-keys) are set correctly.

* Set Default Input and Output Audio devices

Use `pactl` to set your default microphone and speaker.

If you get `pa_context_connect() failed: Connection refused`, then start the audio daemon manually via `pulseaudio --start -D`.

```bash
pactl list sources short                             # List input (microphone) devices
pactl list sinks short                               # List output (speaker) devices

pactl set-default-sink [SINK_NAME || SINK_ID]        # Set default output device
pactl set-default-source [SOURCE_NAME || SOURCE_ID]  # Set default input device
pactl set-sink-volume @DEFAULT_SINK@ 100%            # Set default output volume

# for example,
pactl set-default-source alsa_input.usb-046d_C270_HD_WEBCAM_2CD9A910-02.mono-fallback
pactl set-default-sink alsa_output.platform-bcm2835_audio.stereo-fallback
```

* Launch OM1

```bash Run OM1 turtlebot4 agent
uv run src/run.py turtlebot4
```

On the RPi4, there will be a lengthy delay before OM1 runs. 

### Run OM1 offboard (your laptop)

- Install OM1 on your laptop, following [Install OM1 on your laptop](/getting-started/get-started)
- Install Zenoh on your Mac, PC, or Linux box, following [Installing the Zenoh router](https://zenoh.io/docs/getting-started/installation/)

Run OM1 on your laptop .  

```bash Run Robot
uv run src/run.py turtlebot4
```

Please make sure that your development machine (e.g. your laptop) is running the same version of the Zenoh bridge (e.g. 1.2.1) as the RPi otherwise you will get errors.

#### Interacting with TurtleBot4 from a Remote Computer using Zenoh

Inside `system_hw_test`, there are several scripts for you to interact with the TurtleBot4. For all these scripts, please provide/update the topic names to include your specific namespace. If you do not update the namespaces, the scripts will fail. 

Steer the TurtleBot4 with your keyboard:
Before running the script, make sure you have the correct topic names e.g   
Change the [URID, topic name in turtlebot4_keyboard_movement.py](https://github.com/OpenmindAGI/OM1/blob/c6f0d118bf16c9201403ae459111d4cacc3830dd/system_hw_test/turtlebot4_keyboard_movement.py#L40C9-L40C33) to include your specific namespace.  

NOTE: Remove the first `/` in the topic name.

```bash
self.cmd_vel = "<your_namespace>/pi/cmd_vel"
```

And then run the script.

```bash
uv run turtlebot4_keyboard_movement.py
```
* W - Move Forward
* S - Move Backward
* A - Turn Left
* D - Turn Right

Read TurtleBot4 laser scan, collision, and battery data:  
NOTE: Change the [URID in turtlebot4_laserscan.py](https://github.com/OpenmindAGI/OM1/blob/c6f0d118bf16c9201403ae459111d4cacc3830dd/system_hw_test/turtlebot4_laserscan.py#L60) to your specific namespace. 

```bash
uv run turtlebot4_laserscan.py
```

Read TurtleBot4 Camera PREVIEW (250x250RGB) data:    
NOTE: Change the [URID in turtlebot4_camera_opencv.py](https://github.com/OpenmindAGI/OM1/blob/c6f0d118bf16c9201403ae459111d4cacc3830dd/system_hw_test/turtlebot4_camera_opencv.py#L22) to your specific namespace. 

```bash
uv run turtlebot4_camera_opencv.py
```

## Expected ROS2 Topics for a Correctly Configured System

On the TurtleBot4 command line, run `ros2 topic list`. Topics with a `pi` prefix originate from the RPi, and topics without a prefix are from the Create3. If you do not see any non-prefixed topics, your Create3 is not talking correctly to the RPi.

```bash
/OM742d35Cc6634/c3/battery_state
/OM742d35Cc6634/c3/cmd_vel
/OM742d35Cc6634/c3/dock_status
/OM742d35Cc6634/c3/hazard_detection
/OM742d35Cc6634/c3/imu
/OM742d35Cc6634/c3/odom
/OM742d35Cc6634/c3/robot_state/transition_event
/OM742d35Cc6634/c3/static_transform/transition_event
/OM742d35Cc6634/c3/tf
/OM742d35Cc6634/c3/tf_static

/OM742d35Cc6634/pi/battery_state
/OM742d35Cc6634/pi/cmd_vel
/OM742d35Cc6634/pi/diagnostics
/OM742d35Cc6634/pi/diagnostics_agg
/OM742d35Cc6634/pi/diagnostics_toplevel_state
/OM742d35Cc6634/pi/dock_status
/OM742d35Cc6634/pi/function_calls
/OM742d35Cc6634/pi/hazard_detection
/OM742d35Cc6634/pi/hmi/buttons
/OM742d35Cc6634/pi/hmi/display
/OM742d35Cc6634/pi/hmi/display/message
/OM742d35Cc6634/pi/hmi/led
/OM742d35Cc6634/pi/imu
/OM742d35Cc6634/pi/interface_buttons
/OM742d35Cc6634/pi/ip
/OM742d35Cc6634/pi/joint_states
/OM742d35Cc6634/pi/joy
/OM742d35Cc6634/pi/joy/set_feedback
/OM742d35Cc6634/pi/mouse
/OM742d35Cc6634/pi/oakd/imu/data
/OM742d35Cc6634/pi/oakd/rgb/preview/camera_info
/OM742d35Cc6634/pi/oakd/rgb/preview/image_raw
/OM742d35Cc6634/pi/oakd/rgb/preview/image_raw/compressed
/OM742d35Cc6634/pi/oakd/rgb/preview/image_raw/compressedDepth
/OM742d35Cc6634/pi/oakd/rgb/preview/image_raw/theora
/OM742d35Cc6634/pi/robot_description
/OM742d35Cc6634/pi/scan
/OM742d35Cc6634/pi/tf
/OM742d35Cc6634/pi/tf_static
/OM742d35Cc6634/pi/wheel_status

/diagnostics
/parameter_events
/rosout
```

## Building the Docker Dual Bridge Images

You can build your own dual bridge docker images using the provided `Dockerfile` (see `/system_hw_test/turtlebot_zenoh/Dockerfile`):

```bash
docker build -t my-username/my-image .
docker push my-username/my-image
```

Useful docker commands
```bash
sudo docker compose pull # pull latest image

# Images
sudo docker images
sudo docker rmi IMAGE_ID --force

# Containers
sudo docker ps -a
sudo docker attach CONTAINER_ID # to stream logs
sudo docker exec -it CONTAINER_ID sh # to get a shell
sudo docker kill CONTAINER_ID
```

## Debugging Commands

Webcam debugging:

```bash
lsusb
sudo apt install v4l-utils
v4l2-ctl --list-devices
v4l2-ctl -d /dev/video0 --stream-mmap --all
```
